3D Graphics Programming with QuickDraw 3D 1.5.4

Setting Up Transformation Matrices

QuickDraw 3D provides routines that you can use to configure matrices to be used as geometric transformations. You must already have allocated the memory for a matrix before calling one of these routines.

All functions operating on 3-by-3 matrices assume that the resulting transform matrices are to be used to transform only homogeneous two-dimensional data types (such as TQ3RationalPoint3D ). Similarly, all functions operating on 4-by-4 matrices assume that the resulting transform matrices are to be used to transform only homogeneous three-dimensional data types (such as TQ3RationalPoint4D ).

You specify an angle (for example, for Q3Matrix3x3_SetRotateAboutPoint ) by passing a value that is interpreted in radians. If you prefer to use degrees, QuickDraw 3D provides C language macros that convert radians into degrees.

Q3Matrix3x3_SetTranslate

You can use the Q3Matrix3x3_SetTranslate function to configure a 3-by-3 translation transformation matrix.



 
TQ3Matrix3x3 *Q3Matrix3x3_SetTranslate (

                     TQ3Matrix3x3 *matrix3x3, 

                     float xTrans, 

                     float yTrans);

matrix3x3: A 3-by-3 matrix.
xTrans: The desired amount of translation along the x coordinate axis.
yTrans: The desired amount of translation along the y coordinate axis.

DESCRIPTION

The Q3Matrix3x3_SetTranslate function returns, as its function result and in the matrix3x3 parameter, a transformation matrix that translates an object by the amount xTrans along the x coordinate axis and by the amount yTrans along the y coordinate axis.

Q3Matrix3x3_SetScale

You can use the Q3Matrix3x3_SetScale function to configure a 3-by-3 scaling transformation matrix.



 
TQ3Matrix3x3 *Q3Matrix3x3_SetScale (

                     TQ3Matrix3x3 *matrix3x3, 

                     float xScale, 

                     float yScale);

matrix3x3: A 3-by-3 matrix.
xScale: The desired amount of scaling along the x coordinate axis.
yScale: The desired amount of scaling along the y coordinate axis.

DESCRIPTION

The Q3Matrix3x3_SetScale function returns, as its function result and in the matrix3x3 parameter, a scaling matrix that scales an object by the amount xScale along the x coordinate axis and by the amount yScale along the y coordinate axis.

Q3Matrix3x3_SetRotateAboutPoint

You can use the Q3Matrix3x3_SetRotateAboutPoint function to configure a 3-by-3 rotation transformation matrix.



 
TQ3Matrix3x3 *Q3Matrix3x3_SetRotateAboutPoint (

                     TQ3Matrix3x3 *matrix3x3, 

                     const TQ3Point2D *origin, 

                     float angle);

matrix3x3: A 3-by-3 matrix.
origin: The desired origin of rotation.
angle: The desired angle of rotation, in radians.

DESCRIPTION

The Q3Matrix3x3_SetRotateAboutPoint function returns, as its function result and in the matrix3x3 parameter, a rotation matrix that rotates an object by the angle angle around the point origin .

Q3Matrix4x4_SetTranslate

You can use the Q3Matrix4x4_SetTranslate function to configure a 4-by-4 translation transformation matrix.



 
TQ3Matrix4x4 *Q3Matrix4x4_SetTranslate (

                     TQ3Matrix4x4 *matrix4x4, 

                     float xTrans, 

                     float yTrans, 

                     float zTrans);

matrix4x4: A 4-by-4 matrix.
xTrans: The desired amount of translation along the x coordinate axis.
yTrans: The desired amount of translation along the y coordinate axis.
zTrans: The desired amount of translation along the z coordinate axis.

DESCRIPTION

The Q3Matrix4x4_SetTranslate function returns, as its function result and in the matrix4x4 parameter, a transformation matrix that translates an object by the amount xTrans along the x coordinate axis, by the amount yTrans along the y coordinate axis, and by the amount zTrans along the z coordinate axis.

Q3Matrix4x4_SetScale

You can use the Q3Matrix4x4_SetScale function to configure a 4-by-4 scaling transformation matrix.



 
TQ3Matrix4x4 *Q3Matrix4x4_SetScale (

                     TQ3Matrix4x4 *matrix4x4, 

                     float xScale, 

                     float yScale, 

                     float zScale);

matrix4x4: A 4-by-4 matrix.
xScale: The desired amount of scaling along the x coordinate axis.
yScale: The desired amount of scaling along the y coordinate axis.
zScale: The desired amount of scaling along the z coordinate axis.

DESCRIPTION

The Q3Matrix4x4_SetScale function returns, as its function result and in the matrix4x4 parameter, a scaling matrix that scales an object by the amount xScale along the x coordinate axis, by the amount yScale along the y coordinate axis, and by the amount zScale along the z coordinate axis.

Q3Matrix4x4_SetRotateAboutPoint

You can use the Q3Matrix4x4_SetRotateAboutPoint function to configure a 4-by-4 rotation transformation matrix.



 
TQ3Matrix4x4 *Q3Matrix4x4_SetRotateAboutPoint (

                     TQ3Matrix4x4 *matrix4x4, 

                     const TQ3Point3D *origin, 

                     float xAngle, 

                     float yAngle, 

                     float zAngle);

matrix4x4: A 4-by-4 matrix.
origin: The desired origin of rotation.
xAngle: The desired angle of rotation around the x component of origin , in radians.
yAngle: The desired angle of rotation around the y component of origin , in radians.
zAngle: The desired angle of rotation around the z component of origin , in radians.

DESCRIPTION

The Q3Matrix4x4_SetRotateAboutPoint function returns, as its function result and in the matrix4x4 parameter, a rotation matrix that rotates an object by the specified angle around the point origin .

Q3Matrix4x4_SetRotateAboutAxis

You can use the Q3Matrix4x4_SetRotateAboutAxis function to configure a 4-by-4 rotate-about-axis transformation matrix.



 
TQ3Matrix4x4 *Q3Matrix4x4_SetRotateAboutAxis (

                     TQ3Matrix4x4 *matrix4x4, 

                     const TQ3Point3D *origin, 

                     const TQ3Vector3D *orientation, 

                     float angle);

matrix4x4: A 4-by-4 matrix.
origin: The desired origin of rotation.
orientation: The desired orientation of the axis of rotation.
angle: The desired angle of rotation, in radians.

DESCRIPTION

The Q3Matrix4x4_SetRotateAboutAxis function returns, as its function result and in the matrix4x4 parameter, an rotate-about-axis matrix that rotates an object by the angle angle around the axis determined by the point origin and the orientation orientation .

Q3Matrix4x4_SetRotate_X

You can use the Q3Matrix4x4_SetRotate_X function to configure a 4-by-4 transformation matrix that rotates objects around the x axis.



 
TQ3Matrix4x4 *Q3Matrix4x4_SetRotate_X (

                     TQ3Matrix4x4 *matrix4x4, 

                     float angle);

matrix4x4: A 4-by-4 matrix.
angle: The desired angle of rotation around the x coordinate axis, in radians.

DESCRIPTION

The Q3Matrix4x4_SetRotate_X function returns, as its function result and in the matrix4x4 parameter, a rotational matrix that rotates an object by the angle angle around the x axis.

Q3Matrix4x4_SetRotate_Y

You can use the Q3Matrix4x4_SetRotate_Y function to configure a 4-by-4 transformation matrix that rotates objects around the y axis.



 
TQ3Matrix4x4 *Q3Matrix4x4_SetRotate_Y (

                     TQ3Matrix4x4 *matrix4x4, 

                     float angle);

matrix4x4: A 4-by-4 matrix.
angle: The desired angle of rotation around the y coordinate axis, in radians.

DESCRIPTION

The Q3Matrix4x4_SetRotate_Y function returns, as its function result and in the matrix4x4 parameter, a rotational matrix that rotates an object by the angle angle around the y axis.

Q3Matrix4x4_SetRotate_Z

You can use the Q3Matrix4x4_SetRotate_Z function to configure a 4-by-4 transformation matrix that rotates objects around the z axis.



 
TQ3Matrix4x4 *Q3Matrix4x4_SetRotate_Z (

                     TQ3Matrix4x4 *matrix4x4, 

                     float angle);

matrix4x4: A 4-by-4 matrix.
angle: The desired angle of rotation around the z coordinate axis, in radians.

DESCRIPTION

The Q3Matrix4x4_SetRotate_Z function returns, as its function result and in the matrix4x4 parameter, a rotational matrix that rotates an object by the angle angle around the z axis.

Q3Matrix4x4_SetRotate_XYZ

You can use the Q3Matrix4x4_SetRotate_XYZ function to configure a 4-by-4 transformation matrix that rotates objects around all three coordinate axes.



 
TQ3Matrix4x4 *Q3Matrix4x4_SetRotate_XYZ (

                     TQ3Matrix4x4 *matrix4x4, 

                     float xAngle, 

                     float yAngle, 

                     float zAngle);

matrix4x4: A 4-by-4 matrix.
xAngle: The desired angle of rotation around the x axis, in radians.
yAngle: The desired angle of rotation around the y axis, in radians.
zAngle: The desired angle of rotation around the z axis, in radians.

DESCRIPTION

The Q3Matrix4x4_SetRotate_XYZ function returns, as its function result and in the matrix4x4 parameter, a rotational matrix that rotates an object by the specified angles around the x , y , and z axes.

Q3Matrix4x4_SetRotateVectorToVector

You can use the Q3Matrix4x4_SetRotateVectorToVector function to configure a 4-by-4 transformation matrix that rotates objects around the origin in such a way that a transformed vector matches a given vector.



 
TQ3Matrix4x4 *Q3Matrix4x4_SetRotateVectorToVector (

                     TQ3Matrix4x4 *matrix4x4, 

                     const TQ3Vector3D *v1, 

                     const TQ3Vector3D *v2);

matrix4x4: A 4-by-4 matrix.
v1: A three-dimensional vector.
v2: A three-dimensional vector.

DESCRIPTION

The Q3Matrix4x4_SetRotateVectorToVector function returns, as its function result and in the matrix4x4 parameter, a rotational matrix that rotates objects around the origin in such a way that the transformed vector v1 matches the vector v2 . Both v1 and v2 should be normalized.

Q3Matrix4x4_SetQuaternion

You can use the Q3Matrix4x4_SetQuaternion function to configure a 4-by-4 quaternion transformation matrix.



 
TQ3Matrix4x4 *Q3Matrix4x4_SetQuaternion (

                     TQ3Matrix4x4 *matrix, 

                     const TQ3Quaternion *quaternion);

matrix: A 4-by-4 matrix.
quaternion: A quaternion.

DESCRIPTION

The Q3Matrix4x4_SetQuaternion function returns, as its function result and in the matrix parameter, a 4-by-4 matrix that represents the quaternion specified by the quaternion parameter.